#H1: pod..List

Acts as a standard Python list and is implemented using an SQL table to provide speed and scalability.  

#H2: pod..List Constructor 

{{{

class List(object):
    def __init__(self, name = None, list = None):
        ...
}}}

<SA>
#ROW: name: If a string is provided, first the database is searched to see if a #PC_pod..List exists of that name.  
            If it does, that list is returned and a new list is not created.  If not, a new list is created.  
#ROW: list: If provided, this list is added to the list using self.extend(L = list) 
</SA>

#H2: pod..List Methods

All methods of a standard Python list are provided. 

Common operations such as get/set/del item, forward slicing, append, extend, len, and iterate are performed 
efficiently using SQL (including using negative integer indices to get/set/del). 

Certain methods require the entire list to be brought into memory to be processed and restored.  These include: 

  * Slicing backwards using negative integers. (Forward slicing uses SQL however). 

  * Setting list using slices.
  
  * Deleting list using slices. 
  
  * #PC_contains
  
  * #PC_pop

  * #PC_insert
  
  * #PC_remove
  
  * #PC_index
  
  * #PC_count
  
  * #PC_sort
  
  * #PC_reverse 
  
 
 
 
#H1: pod..Ordered Dict

Acts as a standard Python dict and is implemented using an SQL table to provide speed and scalability.  However, unlike
a Python dict, results are returned in the order they are added.  This is due to the fact that the datastructure is built
on a Python dict which preserves order. 

#H2: pod..Ordered Dict Constructor 

{{{

class OrderedDict(pod..List):
    def __init__(self, name = None, dict = None):
        ...
}}}

<SA>
#ROW: name: If a string is provided, first the database is searched to see if a #PC_pod..List exists of that name.  
            If it does, that list is returned and a new list is not created.  If not, a new list is created.  
#ROW: list: If provided, this dict is added using self.update(other = dict) 
</SA>

#H2: pod..Ordered Dict Methods

All methods of a standard Python dict are provided with the exception of #PC_pop and #PC_popitem. 

#H2: Special Considerations. 

Most importantly, keys can only be strings or ints.  If strings, standard dict methods are called. 

Since #PC_OrderedDict subclasses #PC_pod..List, if #PC_int or #PC_slice keys are provided, #PC_pod..List
methods are used in place of standard dict argument.  

Also, all #PC_pod.collection.List are available.  Just note, the key will not be set.

#H1: Notes on the importance of pod.collection objects in pod. 

But because of pod's hybrid cPickle / SQL architecture, we just want to point out that often
you can use a relational datastructure using SQL to create collections without using the 
#PC_pod.collection objects.  

We provide collections, however, because they are the most flexible (since they can accept any 
type of object) and implement the full Python collection API (e.g. like slicing, 
a negative integer index, contains, iteritems, etc). But if you don't need this full interface, sometimes the same 
objective can be reached more concisely using a table relation.  

The right choice depends on application -- 
pod tries to stay out of your way and let you choose the best tool for the job. 

#H2: Using a standard relational foreign key. 

Using pod columns, you can create a relational key to emulate a list.  Let's look at two ways of tracking
all entries within a blog: 

{{{

# First way, using #PC_pod.collection.List

class Blog(pod.Object):
    
    def __init__(self):
        self.entries = pod.collection.List()

class Entry(pod.Object):
     
    def __init__(self, blog):
        blog.entries.append(self)

blog  = Blog()
entry = Entry(blog = blog)
entry = Entry(blog = blog)
entry = Entry(blog = blog)

db.commit()
 
for entry in blog.entries:
    print blog.entry 
 
# Next, way using a relational table

class Blog(pod.Object):
    pass 
    
class Entry(pod.Object):

    blog = pod.column.Object(index = True)
    
    def __init__(self, blog): 
        self.blog = blog

blog  = Blog()
entry = Entry(blog = blog)
entry = Entry(blog = blog)
entry = Entry(blog = blog)

db.commit()

for entry in Entry.blog == blog:
    print entry    

}}}

Just to point out that this list is 'typed' -- i.e. all members must be of type Entry.  
A #PC_pod.collection list, on the other hand, can accept objects of any type. 


#H2: Using any pod.Object as scalable dictionary.

Here, we simply point out that -- since object attributes are stored on a attribute by attribute 
basis -- that any #pod.Object is in itself a scalable dictionary.  It's just that the standard
dict methods are not available.  If you want an object which is both scalable and works just like
a dictionary, use #pod.collection.OrderedDict. 

  

